# Fetching a list of Invoices

This endpoint returns structured Invoice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `invoices` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

Endpoint: GET /invoices
Version: 1.0.0

## Query parameters:

  - `created_after` (string)
    Filter for records created after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `created_before` (string)
    Filter for records created before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `external_reference_external_message` (string)
    Filter the objects based on the external message of their associated external references. This is an exact match.

  - `external_reference_external_status` (string)
    Filter by the status of the external object in the external system.

  - `external_reference_service_model` (string)
    Filter by the type of the external object this external reference belongs to.

  - `external_reference_service_model_ref` (integer)
    Filter by the id of the external object this external reference belongs to.

  - `external_reference_service_model_refs` (string)
    Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs.

  - `external_reference_service_name` (string)
    Filter by the name of the provider for integration.

  - `external_reference_status` (string)
    Filter by the status of the integration, this can be successful or fail.

  - `has_external_references` (boolean)
    Filter by whether or not the object has external references.

  - `include` (string)
    Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `additional_items` (AdditionalItem) - When included, the `additional_item_ids` array will reference all additional items included in the invoice.
- `billing_milestones` (BillingMilestone) - When included, the `billing_milestone_ids` array will reference all billing milestones included in the invoice.
- `expenses` (Expense) - When included, the `expense_ids` array will reference all expenses included in the invoice.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.
- `fixed_fee_items` (FixedFeeItem) - When included, the `fixed_fee_items` array will reference all fixed fee items included in the invoice.
- `recipient` (User) - The User who received the invoice. Namely, the client lead at the time that the invoice
was created (or null, if no lead client existed at the time).
- `time_entries` (TimeEntry) - When included, the `time_entry_ids` array will reference all time entries included in the invoice.
- `user` (User) - The user who created the invoice.
- `workspaces` (Workspace) - When included, the `workspace_ids` array will reference all projects covered by the invoice.

  - `only` (string)
    Allows you to request one or more resources directly by ID. Multiple IDs can be supplied
in a comma separated list, like `GET /api/v1/workspaces.json?only=5,6,7`.

  - `order` (string)
    Supply `order` with the name of a valid sort field for the endpoint and a direction.

Valid values: `created_at:asc`, `created_at:desc`, `id:asc`, `id:desc`, `invoice_date:asc`, `invoice_date:desc`, `updated_at:asc`, and `updated_at:desc`.

  - `page` (integer)

  - `paid` (boolean)
    When `true` is passed, only paid invoices are returned.

  - `pending` (boolean)
    When `true` is passed, only non-accepted, non-draft invoices are returned.

  - `per_page` (integer)

  - `updated_after` (string)
    Filter for records updated after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `updated_before` (string)
    Filter for records updated before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.

  - `user_invoice_number` (string)
    Provide one or more user invoice numbers, separated by commas. When provided, only invoices
              with the specified user invoice numbers will be returned.

  - `within_dates` (string)
    Provide a date range in 2000-01-01:2000-12-31 format. When provided, only invoices created
              within the specified range will be returned.

  - `without_drafts` (boolean)
    When `true` is passed, draft invoices will not be returned.

  - `without_external_reference_service_name` (string)
    Exclude by the existence of an external reference with the specified service name.

  - `workspace_id` (string)
    Provide one or more workspace IDs, separated by commas. If present, only invoices
              in the provided projects will be returned.

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)